home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / g_man / cat3 / ftn / lmdef.z / lmdef
Encoding:
Text File  |  2002-10-03  |  20.4 KB  |  397 lines
  1.  
  2.  
  3.  
  4. llllmmmmddddeeeeffff((((3333GGGG))))                                                            llllmmmmddddeeeeffff((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      llllmmmmddddeeeeffff - defines or modifies a material, light source, or lighting model
  10.  
  11. FFFFOOOORRRRTTTTRRRRAAAANNNN 77777777 SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  12.      ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee llllmmmmddddeeeeffff((((ddddeeeeffffttttyyyyppppeeee,,,, iiiinnnnddddeeeexxxx,,,, nnnnpppp,,,, pppprrrrooooppppssss))))
  13.      iiiinnnntttteeeeggggeeeerrrr****4444 ddddeeeeffffttttyyyyppppeeee,,,, iiiinnnnddddeeeexxxx,,,, nnnnpppp
  14.      rrrreeeeaaaallll pppprrrrooooppppssss((((nnnnpppp))))
  15.  
  16. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  17.      _d_e_f_t_y_p_e   expects the category in which to create a new definition, or
  18.                the category of the definition to be modified.  There are three
  19.                categories, each with its own symbolic constants:
  20.  
  21.                DDDDEEEEFFFFMMMMAAAATTTT indicates that a material is being defined or modified.
  22.  
  23.                DDDDEEEEFFFFLLLLIIIIGGGG indicates that a light source is being defined or
  24.                modified.
  25.  
  26.                DDDDEEEEFFFFLLLLMMMMOOOO indicates that a lighting model is being defined or
  27.                modified.
  28.  
  29.      _i_n_d_e_x     expects the index into the table of stored definitions.  There
  30.                is a unique definitions table for each category of definition
  31.                created by this routine  (materials, light sources, or lighting
  32.                models).  Indexes within each of these categories are
  33.                independent.  In each category, index 0 is reserved as a null
  34.                definition, and cannot be redefined.
  35.  
  36.      _n_p        expects the number of symbols and floating point values in
  37.                _p_r_o_p_s, including the termination symbol LLLLMMMMNNNNUUUULLLLLLLL.  If _n_p is zero,
  38.                it is ignored.  Operation over network connections is more
  39.                efficient when _n_p is correctly specified, however.
  40.  
  41.      _p_r_o_p_s     expects the array of floating point symbols and values that
  42.                define, or modify the definition of, the material, light
  43.                source, or lighting model named _i_n_d_e_x.  _p_r_o_p_s must contain a
  44.                sequence of lighting symbols, each followed by the appropriate
  45.                number of floating point values.  The last symbol must be
  46.                LLLLMMMMNNNNUUUULLLLLLLL, which is itself not followed by any values.
  47.  
  48.      Different symbols are used to define materials, light sources, and
  49.      lighting models.  The symbols used when _d_e_f_t_y_p_e is DDDDEEEEFFFFMMMMAAAATTTT are:
  50.  
  51.           AAAALLLLPPPPHHHHAAAA specifies the transparency of the material.  It is followed by
  52.           a single floating point value in the range 0.0 through 1.0.  This
  53.           alpha value is assigned to all RGB triples generated by the lighting
  54.           model.  Alpha is ignored by systems that do not support blending,
  55.           and is always valid in systems that do, regardless of whether alpha
  56.           bitplanes are installed in the system.  The default alpha value is
  57.           1.0.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. llllmmmmddddeeeeffff((((3333GGGG))))                                                            llllmmmmddddeeeeffff((((3333GGGG))))
  71.  
  72.  
  73.  
  74.           AAAAMMMMBBBBIIIIEEEENNNN specifies the ambient reflectance of the material.  It is
  75.           followed by three floating point values, typically in the range 0.0
  76.           through 1.0, specifying red, green, and blue reflectances.  The
  77.           default ambient reflectances are 0.2, 0.2, and 0.2.
  78.  
  79.           CCCCOOOOLLLLOOOORRRRIIII specifies the material properties used when lighting in color
  80.           map mode.  This property is ignored while the current framebuffer is
  81.           in RGB mode, as are most other material properties when the current
  82.           framebuffer is in color map mode.  (Material property SSSSHHHHIIIINNNNIIIINNNN is used
  83.           in color map mode.)  It is followed by three floating point values,
  84.           assigning the ambient, diffuse, and specular material color indices.
  85.           The default color indices are 0.0, 127.5, and 255.0.
  86.  
  87.           DDDDIIIIFFFFFFFFUUUUSSSS specifies the diffuse reflectance of the material.  It is
  88.           followed by three floating point values, typically in the range 0.0
  89.           through 1.0, specifying red, green, and blue diffuse reflectances.
  90.           The default diffuse reflectances are 0.8, 0.8, and 0.8.
  91.  
  92.           EEEEMMMMIIIISSSSSSSSIIII specifies the color of light emitted by the material.  It is
  93.           followed by three floating point values, typically in the range 0.0
  94.           through 1.0, specifying red, green, and blue emitted light levels.
  95.           The default emission levels are 0.0, 0.0, and 0.0.
  96.  
  97.           SSSSHHHHIIIINNNNIIIINNNN specifies the specular scattering exponent, or the shininess,
  98.           of the material.  It is followed by a single floating point value in
  99.           the range 0.0 through 128.0.  Higher values result in smaller, hence
  100.           more shiny, specular highlights.  The default shininess is 0.0,
  101.           which effectively disables specular reflection.
  102.  
  103.           SSSSPPPPEEEECCCCUUUULLLL specifies the specular reflectance of the material.  It is
  104.           followed by three floating point values, typically in the range 0.0
  105.           through 1.0, specifying red, green, and blue specular reflectances.
  106.           The default specular reflectances are 0.0, 0.0, and 0.0.
  107.  
  108.      The symbols used when _d_e_f_t_y_p_e is DDDDEEEEFFFFLLLLIIIIGGGG are:
  109.  
  110.           AAAAMMMMBBBBIIIIEEEENNNN specifies the ambient light associated with the light source.
  111.           It is followed by three floating point values, typically in the
  112.           range 0.0 through 1.0, specifying red, green, and blue ambient light
  113.           levels.  The default ambient levels are 0.0, 0.0, and 0.0.
  114.  
  115.           LLLLCCCCOOOOLLLLOOOORRRR specifies the color and intensity of the light that is
  116.           emitted from the light source.  It is followed by three floating
  117.           point values, typically in the range 0.0 through 1.0, specifying the
  118.           levels of red, green, and blue light emitted from the light source.
  119.           The default light colors are 1.0, 1.0, and 1.0.
  120.  
  121.           PPPPOOOOSSSSIIIITTTTIIII specifies the position of the light source in the scene.  It
  122.           is followed by four floating point values, specifying _x, _y, _z, and _w
  123.           of the light source position in object-coordinates.  If _w is
  124.           specified as 0.0, the light source is taken to be infinitely distant
  125.           from the origin of the coordinate system.  In this case _x, _y, and _z
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. llllmmmmddddeeeeffff((((3333GGGG))))                                                            llllmmmmddddeeeeffff((((3333GGGG))))
  137.  
  138.  
  139.  
  140.           specify the direction from the origin to the infinitely distant
  141.           light source.  There is typically a performance penalty associated
  142.           with light sources that are not infinitely distant.  The default
  143.           light source position is at infinity directly behind the viewpoint,
  144.           location (0.0, 0.0, 1.0, 0.0).  The location of the light source is
  145.           transformed by the current ModelView matrix when the source is bound
  146.           (see llllmmmmbbbbiiiinnnndddd).
  147.  
  148.           SSSSPPPPOOOOTTTTDDDDIIII specifies the direction that a spot light source emits its
  149.           light.  It is followed by three floating point values, specifying _x,
  150.           _y, and _z direction vectors in object-coordinates.  These vectors are
  151.           normalized automatically.  The direction is ignored if the light
  152.           source is not a spot light.  By default the spot light points down
  153.           the negative _z axis, direction (0.0, 0.0, -1.0).  The direction is
  154.           transformed by the current ModelView matrix when the light source is
  155.           bound (see llllmmmmbbbbiiiinnnndddd).
  156.  
  157.           SSSSPPPPOOOOTTTTLLLLIIII indicates that the light source is to be treated as a spot
  158.           light.  (The light source must not be positioned at infinity.)  It
  159.           is followed by two floating point values, specifying the _e_x_p_o_n_e_n_t
  160.           and the _s_p_r_e_a_d of the light cone.  _e_x_p_o_n_e_n_t controls intensity as a
  161.           function of angle from the spot light direction.  Its range is 0.0
  162.           through 128.0, where 0.0 results in constant intensity throughout
  163.           the cone, and 128.0 results in the sharpest dropoff of intensity as
  164.           angle from spot direction increases.  _s_p_r_e_a_d is the angle in
  165.           degrees, measured from the spot light direction, beyond which the
  166.           cone is attenuated to zero intensity.  Currently only _s_p_r_e_a_d values
  167.           in the range 0.0 through 90.0, and the special value 180.0, are
  168.           supported.  By default _e_x_p_o_n_e_n_t is 0.0 and _s_p_r_e_a_d is 180.0,
  169.           effectively disabling spot lighting.
  170.  
  171.      The symbols used when _d_e_f_t_y_p_e is DDDDEEEEFFFFLLLLMMMMOOOO are:
  172.  
  173.           AAAAMMMMBBBBIIIIEEEENNNN specifies an additional ambient light level that is
  174.           associated with the entire scene, rather than with a light source.
  175.           This light is added to the ambient light associated with each light
  176.           source to yield the total ambient light in the scene.  AAAAMMMMBBBBIIIIEEEENNNN is
  177.           followed by three floating point values, typically in the range 0.0
  178.           through 1.0, specifying red, green, and blue ambient light levels.
  179.           The default lighting model ambient light levels are 0.2, 0.2, and
  180.           0.2.
  181.  
  182.           AAAATTTTTTTTEEEENNNNUUUU specifies the constant and linear attenuation factors
  183.           associated with all non-infinite light sources.  It is followed by
  184.           two floating point values in the range 0.0 through positive
  185.           infinity.  The first attenuation factor is used to directly reduce
  186.           the effect of a light source on objects in the scene.  The second
  187.           factor specifies attenuation that is proportional to the distance of
  188.           the light source from the object being lighted.  The default
  189.           constant and linear attenuations are 1.0 and 0.0, effectively
  190.           disabling constant and linear attenuation.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. llllmmmmddddeeeeffff((((3333GGGG))))                                                            llllmmmmddddeeeeffff((((3333GGGG))))
  203.  
  204.  
  205.  
  206.           AAAATTTTTTTTEEEENNNN2222 specifies the second-order attenuation factor associated with
  207.           all non-infinite light sources.  It is followed by a single floating
  208.           point value in the range 0.0 through positive infinity.  This factor
  209.           specifies attenuation that is proportional to the square of the
  210.           distance of the light source from the object being lighted.  The
  211.           default second-order attenuation is 0.0, effectively disabling
  212.           second-order attenuation.
  213.  
  214.           LLLLOOOOCCCCAAAALLLLVVVV specifies whether reflection calculations are done based on a
  215.           local or infinitely distant viewpoint.  It is followed by a single
  216.           floating point value, which must be either 0.0 or 1.0.  The value
  217.           0.0 indicates that the viewpoint is to be (0.0, 0.0, _i_n_f_i_n_i_t_y) in
  218.           eye-coordinates, hence infinitely distant from all objects in the
  219.           scene.  The value 1.0 indicates that the viewpoint is to be
  220.           (0.0, 0.0, 0.0) in eye-coordinates, hence local.  There is typically
  221.           a performance penalty associated with a local viewpoint.  By default
  222.           the viewpoint is infinitely distant.
  223.  
  224.           TTTTWWWWOOOOSSSSIIIIDDDD specifies whether lighting calculations are done assuming
  225.           that only frontfacing polygons are visible, or are corrected for
  226.           each polygon based on whether it is frontfacing or backfacing.  It
  227.           is followed by a single floating point value, which must be either
  228.           0.0 or 1.0.  The value 0.0 specifies a lighting model that is
  229.           correct only for polygons whose visible face is the facet for which
  230.           normals have been provided.  The value 1.0 specifies a lighting
  231.           model that is correct for both frontfacing and backfacing polygons.
  232.           When TTTTWWWWOOOOSSSSIIIIDDDD is 1.0, vertex normals are reversed (all components
  233.           multiplied by -1.0) for all vertices of backfacing polygons.  Thus,
  234.           for two-sided lighting to operate correctly, normals must be
  235.           specified for the facet whose screen rotation is counter-clockwise
  236.           (i.e. for frontfacing facets).  If a material is bound to BBBBAAAACCCCKKKKMMMMAAAA,
  237.           this material is used to light backfacing polygons (see llllmmmmbbbbiiiinnnndddd).
  238.           Otherwise, both frontfacing and backfacing polygons are lighted
  239.           using MMMMAAAATTTTEEEERRRRIIII.
  240.  
  241.           Lighting calculations for all primitives other than polygons, such
  242.           as points, lines, and characters, are unaffected by the TTTTWWWWOOOOSSSSIIIIDDDD flag.
  243.           By default two-sided lighting is disabled.
  244.  
  245. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  246.      llllmmmmddddeeeeffff either defines a new material, light source, or lighting model, or
  247.      modifies the definition of a currently defined material, light source, or
  248.      lighting model.  _d_e_f_t_y_p_e specifies whether a material, light source, or
  249.      lighting model is being defined or modified.  _i_n_d_e_x is the name of the
  250.      material, light source, or lighting model.  _p_r_o_p_s is a list of attribute
  251.      tokens, each followed by one or more floating point values, that
  252.      initializes or modifies the definition.  The last attribute token in the
  253.      array must be LLLLMMMMNNNNUUUULLLLLLLL.
  254.  
  255.      When llllmmmmddddeeeeffff is first called with a particular _d_e_f_t_y_p_e/_i_n_d_e_x combination,
  256.      the material, light source, or lighting model of name _i_n_d_e_x is created
  257.      with the attributes specified in _p_r_o_p_s, and with default values for all
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. llllmmmmddddeeeeffff((((3333GGGG))))                                                            llllmmmmddddeeeeffff((((3333GGGG))))
  269.  
  270.  
  271.  
  272.      attributes that are not included in _p_r_o_p_s.  Subsequent llllmmmmddddeeeeffff calls with a
  273.      _d_e_f_t_y_p_e/_i_n_d_e_x combination modify only the attributes included in _p_r_o_p_s.
  274.      Prior to the first llllmmmmddddeeeeffff call, _d_e_f_t_y_p_e/_i_n_d_e_x combinations are undefined,
  275.      and cannot be bound (see llllmmmmbbbbiiiinnnndddd).  A definition can be reset to all
  276.      default attributes by passing its _d_e_f_t_y_p_e and _i_n_d_e_x to llllmmmmddddeeeeffff with a null
  277.      attribute list (_p_r_o_p_s contains only LLLLMMMMNNNNUUUULLLLLLLL).  Changes made to a currently
  278.      bound definition are effective immediately.
  279.  
  280.      Lighting calculations are done in a numeric space where 0.0 is black (no
  281.      light) and 1.0 is white (the brightest displayable light).  Color
  282.      attributes are specified in this numeric space, although values outside
  283.      the range 0.0 through 1.0 are allowed.  Lighting specified using llllmmmmddddeeeeffff
  284.      occurs only at the vertices of points, lines, polygons, and at the origin
  285.      of text strings.  At each vertex the contributions of each light source
  286.      are summed with the material emitted light and the lighting model ambient
  287.      (scaled by the material ambient reflectance) to yield the vertex color.
  288.      After each lighting calculation is completed, the computed color
  289.      components are clamped to a maximum value of 1.0, then scaled by 255.0
  290.      prior to interpolation in the framebuffer.
  291.  
  292.      The contribution of each light source is the sum of:
  293.  
  294.           light source ambient color, scaled by material ambient reflectance,
  295.  
  296.           light source color, scaled by material diffuse reflectance and the
  297.           dot product of the vertex normal and the vertex-to-light source
  298.           vector, and
  299.  
  300.           light source color, scaled by material specular reflectance and a
  301.           function of the angle between the vertex-to-viewpoint vector and the
  302.           vertex-to-light source vector.
  303.  
  304.      Material 0, light source 0, and lighting model 0 are null definitions
  305.      that cannot be changed.
  306.  
  307.      The default material is defined as:
  308.  
  309.           ALPHA          1.0
  310.           AMBIEN         0.2, 0.2, 0.2
  311.           COLORI         0.0, 127.5, 255.0
  312.           DIFFUS         0.8, 0.8, 0.8
  313.           EMISSI         0.0, 0.0, 0.0
  314.           SHININ         0.0
  315.           SPECUL         0.0, 0.0, 0.0
  316.  
  317.  
  318.      The default light source is defined as:
  319.  
  320.           AMBIEN         0.0, 0.0, 0.0
  321.           LCOLOR         1.0, 1.0, 1.0
  322.           POSITI         0.0, 0.0, 1.0, 0.0
  323.           SPOTDI         0.0, 0.0, -1.0
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. llllmmmmddddeeeeffff((((3333GGGG))))                                                            llllmmmmddddeeeeffff((((3333GGGG))))
  335.  
  336.  
  337.  
  338.           SPOTLI         0.0, 180.0
  339.  
  340.  
  341.      The default lighting model is defined as:
  342.  
  343.           AMBIEN         0.2, 0.2, 0.2
  344.           ATTENU         1.0, 0.0
  345.           ATTEN2         0.0
  346.           LOCALV         0.0
  347.           TWOSID         0.0
  348.  
  349.  
  350. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  351.      lmbind, lmcolo, mmode, n, nmode
  352.  
  353. NNNNOOOOTTTTEEEESSSS
  354.      This routine is available only in immediate mode.
  355.  
  356.      Lighting requires that the matrix mode be multi-matrix.  It does not
  357.      operate correctly while mmmmmmmmooooddddeeee is MMMMSSSSIIIINNNNGGGGLLLL.
  358.  
  359.      IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support
  360.      light source attributes SSSSPPPPOOOOTTTTLLLLIIII or SSSSPPPPOOOOTTTTDDDDIIII, or lighting model attributes
  361.      AAAATTTTTTTTEEEENNNN2222 or TTTTWWWWOOOOSSSSIIIIDDDD.  Use ggggeeeettttggggddddeeee to determine which lighting model
  362.      attributes are supported.
  363.  
  364. BBBBUUUUGGGGSSSS
  365.      The results of lighting calculations are clamped to a maximum value of
  366.      1.0, but not to a minimum value of 0.0.  If only positive color
  367.      attributes are specified in the active material, light sources, and
  368.      lighting model, the computed color cannot have negative components.
  369.      However, if negative attributes are specified, care must be taken to not
  370.      produce negative results.
  371.  
  372.      Many attributes are not used by the current color map lighting model.
  373.      Some may be used in future releases.
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.